Saltar al contenido principal

Personalización de Ventana

El módulo BrowserWindow es la base de su aplicación Electron y expone muchas APIs que pueden cambiar el aspecto y comportamiento de las ventanas de tu navegador. En este tutorial, pasaremos por los diferentes casos de uso para personalización de ventanas en macOS, Windows y Linux

Crear ventanas sin bordes​

Una ventana sin marco es una ventana que no tiene chrome. No se debe confundir con el navegador de Google Chrome, la ventana chrome se refiere a las partes de la ventana (ej. . barras de herramientas, controles) que no son parte de la página web.

Para crear una ventana sin marco, necesitas establecer frame a false en las BrowserWindow de BrowserWindow

main.js
const { BrowserWindow } = require('electron')
const win = new BrowserWindow({ frame: false })

Apply custom title bar styles macOS Windows​

Title bar styles allow you to hide most of a BrowserWindow's chrome while keeping the system's native window controls intact and can be configured with the titleBarStyle option in the BrowserWindow constructor.

La aplicación de la opción hidden da como resultado una barra de título oculta y una ventana de contenido de tamaño completo.

main.js
const { BrowserWindow } = require('electron')
const win = new BrowserWindow({ titleBarStyle: 'hidden' })

Controla los semáforos macOS​

En macOS, aplicando la opción hidden se seguirán mostrando los controles de ventana estándar ("semáforos") en la parte superior izquierda

Personaliza el aspecto de tus semáforos en macOS​

El estilo de barra de título customButtonsOnHover ocultará los semáforos hasta que pases el cursor sobre ellos. Esto es útil si desea crear semáforos personalizados en su HTML, pero todavía use la interfaz de usuario nativa para controlar la ventana.

const { BrowserWindow } = require('electron')
const win = new BrowserWindow({ titleBarStyle: 'customButtonsOnHover' })

Personalizar la posición del semáforo en macOS​

Para modificar la posición de los controles de la ventana ("semáforos"), hay dos opciones de configuración disponibles.

Al aplicar un estilo de barra de título hiddenInset se desplazará la entrada vertical del semáforo por una cantidad fija.

main.js
const { BrowserWindow } = require('electron')
const win = new BrowserWindow({ titleBarStyle: 'hiddenInset' })

Si necesita más control sobre la posición de los semáforos, puedes pasar un conjunto de coordenadas a la opción trafficLightPosition en el constructor BrowserWindow.

main.js
const { BrowserWindow } = require('electron')
const win = new BrowserWindow({
  titleBarStyle: 'hidden',
  trafficLightPosition: { x: 10, y: 10 }
})

Mostrar y ocultar los semáforos de manera programada en macOS​

También puede mostrar y ocultar los semáforos de manera programada del proceso principal. El win.setWindowButtonVisibility fuerza que los semáforos se muestren u oculten dependiendo del valor de su parámetro booleano.

main.js
const { BrowserWindow } = require('electron')
const win = new BrowserWindow()
// hides the traffic lights
win.setWindowButtonVisibility(false)

Nota: Dado el número de APIs disponibles, hay muchas maneras de lograr esto. Por ejemplo, combinando frame: false con win.setWindowButtonVisibility(true) producirá el mismo resultado de diseño que la configuración titleBarStyle: 'hidden'.

Superposición de controles de ventana​

La Windows Controls Overlay API es un estándar web que da la opción a las aplicaciones de personalizar la zona de la barra de título cuando se instala en un escritorio. Electron expone esta API a través de la opción de constructor BrowserWindow titleBarOverlay.

Esta opción solo funciona cuando se aplica un titlebarStyle personalizado. Cuando titleBarOverlay está habilitado, los controles de ventanas se exponen en su posición predeterminada , y los elementos DOM no pueden usar el área debajo de esta región.

La opción titleBarOverlay acepta dos formatos de valor diferentes.

Especificar true en cualquiera de las plataformas dará como resultado una región de superposición con los colores predeterminados del sistema:

main.js
const { BrowserWindow } = require('electron')
const win = new BrowserWindow({
  titleBarStyle: 'hidden',
  titleBarOverlay: true
})

En cualquiera de las plataformas titleBarOverlay también puede ser un objeto. La altura de la superposición puede especificarse con la propiedad height. En Windows y Linux, el color de la superposición y se puede especificar usando la propiedad color. En Windows y Linux, el color de la superposición y sus símbolos se pueden especificar utilizando las propiedades color y symbolColor respectivamente. Los formatos rgba(), hsla()y #RRGGBBAA son compatibles para aplicar transparencia.

If a color option is not specified, the color will default to its system color for the window control buttons. De la misma manera, si la opción de altura no se especifica por defecto a la altura predeterminada:

main.js
const { BrowserWindow } = require('electron')
const win = new BrowserWindow({
  titleBarStyle: 'hidden',
  titleBarOverlay: {
    color: '#2f3241',
    symbolColor: '#74b1be',
    height: 60
  }
})

Note: Once your title bar overlay is enabled from the main process, you can access the overlay's color and dimension values from a renderer using a set of readonly JavaScript APIs and CSS Environment Variables.

Create transparent windows​

By setting the transparent option to true, you can make a fully transparent window.

main.js
const { BrowserWindow } = require('electron')
const win = new BrowserWindow({ transparent: true })

Limitaciones​

  • You cannot click through the transparent area. See #1335 for details.
  • Las ventanas transparentes no son redimencionables. Establecer resizable a true puede hacer que una ventana transparente deje de funcionar en algunas plataformas.
  • The CSS blur() filter only applies to the window's web contents, so there is no way to apply blur effect to the content below the window (i.e. other applications open on the user's system).
  • La ventana no será transparente cuando DevTools este abierta.
  • On Windows:
    • Transparent windows will not work when DWM is disabled.
    • Transparent windows can not be maximized using the Windows system menu or by double clicking the title bar. The reasoning behind this can be seen on PR #28207.
  • On macOS:
    • The native window shadow will not be shown on a transparent window.

Create click-through windows​

Para crear una ventana click-through, por ejemplo hacer que la ventana ignore todos los eventos del ratón, puedes llamar la API win.setIgnoreMouseEvents(ignore):

main.js
const { BrowserWindow } = require('electron')
const win = new BrowserWindow()
win.setIgnoreMouseEvents(true)

Forward mouse events macOS Windows​

Ignoring mouse messages makes the web contents oblivious to mouse movement, meaning that mouse movement events will not be emitted. On Windows and macOS, an optional parameter can be used to forward mouse move messages to the web page, allowing events such as mouseleave to be emitted:

main.js
const { BrowserWindow, ipcMain } = require('electron')
const path = require('node:path')

const win = new BrowserWindow({
  webPreferences: {
    preload: path.join(__dirname, 'preload.js')
  }
})

ipcMain.on('set-ignore-mouse-events', (event, ignore, options) => {
  const win = BrowserWindow.fromWebContents(event.sender)
  win.setIgnoreMouseEvents(ignore, options)
})
preload.js
window.addEventListener('DOMContentLoaded', () => {
  const el = document.getElementById('clickThroughElement')
  el.addEventListener('mouseenter', () => {
    ipcRenderer.send('set-ignore-mouse-events', true, { forward: true })
  })
  el.addEventListener('mouseleave', () => {
    ipcRenderer.send('set-ignore-mouse-events', false)
  })
})

This makes the web page click-through when over the #clickThroughElement element, and returns to normal outside it.

Set custom draggable region​

Por defecto, una ventana sin bordes no se puede desplazar. La aplicación necesita especificar -webkit-app-region: drag en CSS para indicarle a Electron cuales regiones son desplazables (como la barra de títulos estándar del sistema operativo). Las aplicaciones también pueden usar -webkit-app-region: no-drag para excluir el área no desplazable de las regiones desplazables. Tenga en cuenta que solo las formas rectangulares son soportadas.

Para hacer que toda la ventana sea desplazable, puedes agregar -webkit-app-region: drag como el estilo de body:

styles.css
body {
  -webkit-app-region: drag;
}

Y tenga en cuenta que si se hace toda la ventana desplazable, se debe marcar los botones como no desplazable, de lo contrario sería imposible para los usuarios hacer clic sobre ellos:

styles.css
button {
  -webkit-app-region: no-drag;
}

Si sólo está configurando una barra de títulos personalizada como arrastrable, también necesita hacer todos los botones en la barra de título no arrastrable.

Tip: disable text selection​

When creating a draggable region, the dragging behavior may conflict with text selection. For example, when you drag the titlebar, you may accidentally select its text contents. To prevent this, you need to disable text selection within a draggable area like this:

.titlebar {
  -webkit-user-select: none;
  -webkit-app-region: drag;
}

Tip: disable context menus​

On some platforms, the draggable area will be treated as a non-client frame, so when you right click on it, a system menu will pop up. To make the context menu behave correctly on all platforms, you should never use a custom context menu on draggable areas.